Skip to content

refactor(guides): move cycle-attachment content to inter-canister-calls#243

Open
marc0olo wants to merge 5 commits into
mainfrom
docs/move-cycles-call-section
Open

refactor(guides): move cycle-attachment content to inter-canister-calls#243
marc0olo wants to merge 5 commits into
mainfrom
docs/move-cycles-call-section

Conversation

@marc0olo
Copy link
Copy Markdown
Member

@marc0olo marc0olo commented May 12, 2026 •
edited
Loading

Summary

  • Moves the ## Calling canisters that require cycles section out of the cycles-management guide and into inter-canister-calls as a new ## Calls with attached cycles section. Attaching cycles to a call is a call mechanic, not an operational management concern.
  • Also moves the ### Accepting cycles in your canister subsection (which was under "Topping up canisters") to the same new section, since it is the callee-side of the same mechanic.
  • Modernizes the moved Motoko examples from the deprecated Cycles.add<system>() imperative style to the current (with cycles = amount) parenthetical syntax, and updates the Rust examples from the low-level msg_cycles_add call to .with_cycles() on the Call builder — consistent with how the rest of inter-canister-calls.mdx is written.
  • Extends the callee example to require a specific fee, trap if the attached amount falls short, and accept exactly that fee — excess is returned to the caller automatically. The original "accept all" pattern was a tip-jar, not representative of how real fee-charging canisters (like the XRC) work.
  • Renames the callee subsection to ### Charging a cycle fee and the example function to compute() returning (), making clear that cycles are payment for work rather than the subject of the function.
  • Fixes icp new proxy --template proxy → icp new proxy --subfolder proxy (no --template flag exists; verified against .sources/icp-cli/docs/reference/cli.md). The bug was present in the original section and carried over during the move.
  • Leaves a precise cross-reference in cycles-management.md pointing to the new location.
  • Updates four inbound links: concepts/cycles.md (×2), guides/chain-fusion/exchange-rates.mdx (×2).

Sync recommendation

hand-written

Closes #231

@marc0olo marc0olo requested a review from a team as a code owner May 12, 2026 08:23
@github-actions
Copy link
Copy Markdown

github-actions Bot commented May 12, 2026 •
edited
Loading

🤖 Here's your preview: https://kwnd6-zaaaa-aaaam-ai7va-cai.icp0.io

@marc0olo
Copy link
Copy Markdown
Member Author

marc0olo commented May 12, 2026

Code review: one CLI command error found.

All Motoko and Rust examples are correct:

  • (with cycles = amount) parenthetical syntax is confirmed correct per the Motoko compiler docs
  • Cycles.accept<system>(available) with mo:core/Cycles and mo:core/Runtime imports is correct
  • .with_cycles(u128) on the Call builder is confirmed in ic-cdk/src/call.rs
  • msg_cycles_available() / msg_cycles_accept() (Rust callee) are correct

Fix needed: The icp new command has no --template flag. The proxy CLI block uses:

icp new proxy --template proxy

The correct flag is --subfolder:

icp new proxy --subfolder proxy

Verified against .sources/icp-cli/docs/reference/cli.md — icp new accepts --subfolder, --git, --path, --branch, --tag, etc. No --template flag exists. This bug was present in the original section in cycles-management.mdx and was carried over unchanged.

@marc0olo
fix(guides): correct icp new flag and extend callee cycles example
5840d83 
- Fix --template -> --subfolder flag on icp new (per cli reference)
- Extend accepting-cycles example to require a specific fee and accept
  exactly that amount; excess is returned to the caller automatically
@marc0olo
Copy link
Copy Markdown
Member Author

marc0olo commented May 12, 2026

Feedback addressed:

  • Fixed icp new proxy --template proxy → icp new proxy --subfolder proxy (verified against .sources/icp-cli/docs/reference/cli.md)
  • Extended "Accepting cycles in the callee" to require a specific fee (100_000_000 as an example constant), trap if available < fee, and accept exactly fee rather than all available cycles — excess is returned to the caller automatically. This matches how real fee-charging canisters (like the XRC) work and avoids silently draining an overpaying caller.

@marc0olo
Copy link
Copy Markdown
Member Author

marc0olo commented May 12, 2026

Re-reviewed after the follow-up commit. All examples are correct:

CLI fix: --subfolder proxy is now in place. Verified against .sources/icp-cli/docs/reference/cli.md.

Improved callee pattern: the new fee-based accept is correct on both sides.

  • Motoko: debug_show fee is a built-in keyword (confirmed in Motoko language manual); Cycles.accept<system>(fee) accepts exactly the fee amount; the Cycles module docs confirm "any remaining available amount is automatically refunded to the caller" on return.
  • Rust: msg_cycles_accept(FEE) with FEE: u128 matches the max_amount: u128 signature in ic-cdk/src/api.rs; the "accept exactly the fee; excess is returned automatically" comment is accurate per IC protocol behavior.

All Motoko/Rust imports, anchor links, and the --id-only / --proxy CLI flags are correct. PR looks good.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

infra: move 'Calling canisters that require cycles' from cycles-management to inter-canister-calls

1 participant

@marc0olo